Text>Draw
=========

Version 1.32
------------

Introduction
~~~~~~~~~~~~
Draw supports text objects. However, a draw text object can have only
a single style (font face, style, size, etc). If it is necessary to
enter a text string containing style changes then one must enter each
part of the string separately, and then drag the components into their
correct positions. Such more complex text strings may be required when
adding e.g. chemical formulae or mathematical equations, to a diagram.

Text>Draw is a simple application intended to ease the entry of text
such as this into Draw or similar applications. The main entry window
shows the text as it will appear when imported into Draw. An example
of a chemical equation is shown below. It includes subscripts, and use
of the MathGreek font (the arrow as well as the nu).

Note that Text>Draw produces a (grouped) text object, not a text area.


Installation
~~~~~~~~~~~~
For a new installation, simply drag and drop the Text>Draw application
into the directory of your choice.

If you have a previous copy of Text>Draw move the old version of
Text>Draw somewhere safe and replace it with the new version.

Usage
~~~~~
!Text>Draw can be run from the desktop by double clicking on the
!Text>Draw icon in a directory viewer to install its icon on the icon
bar. Clicking SELECT on the iconbar icon will open the input window
ready to enter the text you wish to reproduce as a draw object.

The iconbar icon
~~~~~~~~~~~~~~~~
Clicking with SELECT on the iconbar icon will open the main edit
window (see below).

Clicking with ADJUST on the iconbar icon will open the choices window
(see below).

The icon bar menu
~~~~~~~~~~~~~~~~~
Info
----
Shows application information, including the version number, and also
contains a Web button to check the download site for new versions.

Help...
-------
Opens the html help file (this one).

Choices...
----------
Open the Text>Draw choices window (see below). This allows you to
change certain general settings, and also determine the settings in
force when Text>Draw first starts up.

Quit
----
Remove the application from the iconbar.

The main window
~~~~~~~~~~~~~~~
This window behaves as a primitive word processor. Its features are
determined primarily by the requirements for ease of conversion to a
drawfile. Typing at the keyboard enters the text at the caret.
Clicking with Select at any point in the text will place the caret
ready for text entry, or for editing the text. The Delete and
Backspace keys will delete forwards and backwards from the caret in
the normal manner. When entering text, insert mode is always used,
there is no overtype mode. Changing the text must be carried out the
long way, i.e. delete that not required followed by entering the new
text.

Style changes can be accomplished in two ways.
Using the mouse
---------------
At the top of the window is a toolbar. The groups of buttons at the
left are the style buttons. Six font styles are allowed (nominally
plain/normal, bold, italic, bold italic, symbol, and alternative
symbol), but each of these can be set to any font face and style you
wish. A style change is accomplished by clicking on the appropriate
button. To revert to a previous style or the plain style it is
necessary to set it explicity. You cannot 'cancel' a style by clicking
the same style button again.

The other three buttons in this group move the text up or down by the
configured amount (see below in Choices...), allowing superscripts and
subscripts to be entered. Super/sub script mode is cancelled using the
third button of this group (simply going up then down will not come
out of script mode).

Using the keyboard
------------------
It is also possible to use the keyboard to effect style changes. The
complete set of keyboard shortcuts used are as follows:

Ctrl-N  Normal text              Ctrl-U  Superscript
Ctrl-B  Bold   	                 Ctrl-D  Subscript
Ctrl-I  Italic                   Home    Start of text
Ctrl-J  Bold italic              End     End of text
Ctrl-S  Symbol                   Ctrl-X  Delete all
Ctrl-T  Alternative symbol       F1      Help
Enter   Cancel super/subscript   F3      Save as...

Main window extent
~~~~~~~~~~~~~~~~~~
When the application is first run, the size of the main window should
be sufficient for most purposes. However, if you are entering a large
text object (either due to a lot of text or a large font size), then
the window should automatically grow larger, and auto scroll, to keep
the caret within view.

Main window menu
~~~~~~~~~~~~~~~~
The menu attached to the main window offers a small number of options,
most of which are duplicated by button and key short cuts.

Clear all
---------
This action is duplicated by the keypress ctrl-X and by the rightmost
button on the button bar (with the red cross). All the text is
cleared, leaving a blank window. If the data has not been saved a
warning will be issued if that option is set in the application
choices (see below).

Save as
-------
This will open the save as submenu. This submenu is also available
from the save button in the button bar.

Text (simple)
-------------
This will save the data as a text file, using escape sequences to
describe the style changes. This file can be reloaded into Text>Draw
to recreate the object. Note that the reloaded object will take on the
styles that are set at the time the file is reloaded, and therefore
the result may not be the same as the original.

Text (with styles)
------------------
This option is similar, but the file also contains all the style
settings in operation when the file is saved. This means that when the
file is reloaded, the style settings are changed to match those in
force when the file was saved.

Draw
----
This option allows the text to be saved as a draw file. Since each
style change requires a new text object, the objects are saved as a
single group. This means it is easy to move the text around in Draw
(or similar application) without destroying all the formatting. If you
do wish to tinker with the draw object, then it can be ungrouped to
all the component parts. Application to application saving is
supported in addition to saving to a filing system.

Draw (reloadable)
-----------------
This option allows the text to be saved as a tagged object draw file.
Saving as a tagged object allows the object to include all the
original text with styles information. However, the resulting object
is treated differently by Draw. It will be rendered, but it will not
be possible to even move it around, let alone scale or otherwise
change it. This might not seem very useful. However, if it is loaded
into an application such as Ovation Pro, then it can be scaled in the
frame. Since it still contains the original text data, it can
subsequently be saved out as a draw file and this file can be reloaded
in to Text>Draw for editing.

Help...
-------
Opens the HTML help files (which you are currently viewing) in a
browser.

Choices...
~~~~~~~~~~
The settings are grouped into categories which are accessed by
selecting the appropriate tab.

Font styles
-----------
The six font faces (plain, italic, bold, bold italic, and two symbol
styles) can be set up here. Each of the font faces can be changed
using the menu attached to the menu button to the right of the font
name.

In addition, it is possible to choose whether the text should be
kerned. For most purposes, it is better to switch kerning on.

The final settings in this tab specify the text colour. The currently
set colours are shown in the small colour patch, and can be changed by
clicking on the popup menu button to the right. This will show a
standard colour picker dialogue. When a different colour is chosen,
the colour patch will change to reflect the new colour.

The text foreground colour is the colour of the actual text. The
background colour is NOT a complete rectangle behind the text. It is
the colour that is used for the font manager anti-aliasing. By default
this is white. However, if the text is going to be placed on a
coloured background, then the background colour should be set to the
same colour. When the text is over any other colour, then a coloured
fringe will be seen around it due to the anti-aliased pixels. This, of
course, also applies if the background is white, and the text is
placed over a coloured background - the text will have a grey/white
fringe.

Text sizes
----------
The base, or normal size of text, can be set in units of point,
changed using the adjuster arrows to the right of the value.

The next part of the choices dialogue determines how superscripts and
subscripts are dealt with. There are three options.

If you choose Same as base, then all text is in the same size, as set
by the base font size (see above). The Script and Script-script fields
will be shaded.

If you choose Absolute, then the Script and Script-script fields will
become available. The required sizes are set using the associated bump
arrows. The sizes are set in pt.

Finally you can choose to set the Script and Script-script sizes as a
percentage of the base font size, again using the bump arrows. The
advantage of this setting is that if the base size is changed, the
script sizes change in proportion. Using the Absolute setting means
all three settings need to be changed.

Also in this part of the dialogue is another setting associated with
super/sub scripts, viz. the line shift used to produce the
super/subscript. This is set as a percentage of the font size.
Something in the region of 30-50% usually is suitable.

Miscellaneous
-------------
Clear data on viewer close - if this is ticked, then closing the
window will clear the data, so when the viewer is reopened it will be
blank. If the following option is ticked, a warning will be issued if
the data is unsaved.

Warn when unsaved data - if this is ticked, and the current data has
not been saved, then a warning will be issued whenever the data is
cleared or new data is loaded from file. Note that saving as a draw
file does not count as a 'permanent' save.

The action buttons
~~~~~~~~~~~~~~~~~~
At the bottom of the window are four action buttons, Set, Save, Reload
and Cancel.

Set will apply the choices with immediate effect. Any changes made
will last only until Text>Draw is quit.

Save will apply the choices with immediate effect, and will also save
the settings so they will be reloaded when Text>Draw is run on another
occasion.

Reload is a quick way of reverting to the last saved settings if you
have changed and set some for a particular pupose.

Cancel will simply close the dialogue, and any alterations made will
be ignored.

Screenshots
~~~~~~~~~~~
All the screen shots in these pages were obtained using Snapper, a
versatile screen capture application.

Snapper is available from
http://www.chris-johnson.org.uk/software/snap.html

Contact
~~~~~~~
All communication about Text>Draw should be directed to Chris Johnson
(Email:chris@chris-johnson.org.uk). Suggestions for new features are
always welcome.

Web sites
~~~~~~~~~
Chris Johnson's web site is at
http://www.chris-johnson.org.uk/index.html, with his RISC OS software
at http://www.chris-johnson.org.uk/software/index.html.

This document last modified on 29 Oct 2013

*********************************************************************

Copyright (c) 2013, Chris Johnson
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of their
  contributors may be used to endorse or promote products derived
  from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*********************************************************************

